<HTML>
<TITLE>module vert_turb_driver_mod</TITLE>
<BODY BGCOLOR="#AABBCC" TEXT="#332211" >

<DIV ALIGN="CENTER"> <FONT SIZE=1>
<A HREF="#INTERFACE">PUBLIC INTERFACE</A> / 
<A HREF="#ROUTINES">ROUTINES</A> / 
<A HREF="#NAMELIST">NAMELIST</A> / 
<A HREF="#DIAGNOSTICS">DIAGNOSTICS</A> / 
<A HREF="#ERRORS">ERRORS</A>
</FONT>
<BR><BR></DIV><HR>


<H2>Module vert_turb_driver_mod</H2>
<A NAME="HEADER">
<PRE>
     <B>Contact:</B>   Bruce Wyman, Steve Klein
     <B>Reviewers:</B>

</PRE>
</A><!-- END HEADER -->
<!--------------------------------------------------------------------->
<A NAME="OVERVIEW">
<HR>
<H4>OVERVIEW</H4>
<!-- BEGIN OVERVIEW -->
<PRE>

     Controls the selection of schemes to determine diffusion
     coefficents in the free atmosphere and outputs related
     diagnostic quantities.

</PRE>
</A><!-- END OVERVIEW -->
<!--------------------------------------------------------------------->
<A NAME="DESCRIPTION">
<!-- BEGIN DESCRIPTION -->
<PRE>

     The follow processes are controlled by this module:

        1) Mellor-Yamada 2.5 turbulence closure scheme
        2) Generalized diffusivity scheme
        3) Shallow convection scheme
        4) Calculation of gustiness

</PRE>
</A><!-- END DESCRIPTION -->
<!--------------------------------------------------------------------->
<A NAME="MODULES_USED">
<HR>
<H4>OTHER MODULES USED</H4>
<!-- BEGIN MODULES_USED -->
<PRE>

         my25_turb_mod
       diffusivity_mod
      shallow_conv_mod
      diag_manager_mod
      time_manager_mod
         constants_mod
         utilities_mod

</PRE>
</A><!-- END MODULES_USED -->
<!--------------------------------------------------------------------->
<A NAME="INTERFACE">
<HR>
<H4>PUBLIC INTERFACE</H4>
<!-- BEGIN INTERFACE -->
<PRE>

use vert_turb_driver_mod [,only: vert_turb_driver_init,
                                 vert_turb_driver, vert_turb_driver_end]

vert_turb_driver_init - Must be called once before vert_turb_driver to
                        initialize the module (reads namelist input)
                        and other modules used.

vert_turb_driver      - Called every time step to compute diffusion
                        coefficients.

vert_turb_driver_end  - Called at the end of the model run to terminate
                        the vert_turb_driver module and other modules used.

Notes:
 1) A namelist interface controls runtime options and selects fields
    for diagnostics output.
 
</PRE>
</A><!-- END INTERFACE -->
<!--------------------------------------------------------------------->
<A NAME="ROUTINES">
<HR>
<H4>PUBLIC ROUTINES</H4>
<!-- BEGIN ROUTINES -->
<PRE>

<b>call vert_turb_driver_init</b> (id, jd, kd, axes, Time)

input

    id, jd    number of horizontal grid points in the global
              fields along the i and j axis, repectively.
                 [integer]

    kd        number of vertical points in a column of the atmosphere
                 [integer]

    axes      The axis indices that are returned by previous calls to
              diag_axis_init. The values of this array correspond to the
              x, y, full (p)level, and half (p)level axes. These are the
              axes that diagnostic fields are output on.
                 [integer, dimension(4)]

    Time      The current time.  [time_type]

---------------------------------------------------------------------

<b>call vert_turb_driver</b> (is, js, Time, Time_next, dt, frac_land,
                       p_half, p_full, z_half, z_full,
                       u_star, b_star, rough, u, v, t, q, 
                       um, vm, tm, qm, udt, vdt, tdt, qdt,
                       diff_t, diff_m, gust [, mask, kbot] )

input

    is         starting i index for current window [integer]

    js         starting j index for current window [integer]

    Time       time at the current time level (tau) [time_type]

    Time_next  time at the next time level (tau+1) [time_type]

    dt         time step in seconds (from tau-1 to tau+1 if leapfrog)
                 [real]

    frac_land  fraction (0. to 1.) of surface which covered by land
                 [real, dimension(:,:)]

    p_half     pressure at half model levels [real, dimension(:,:,nlev+1)]

    p_full     pressure at full model levels [real, dimension(:,:,nlev)]

    z_half     height (in meters) at half model levels
                 [real, dimension(:,:,nlev+1)]

    z_full     height (in meters) at full model levels
                 [real, dimension(:,:,nlev)]

    u_star     friction velocity (m/s) for the surface layer
                 [real, dimension(:,:)]

    b_star     bouyancy scale (deg K/m ???) for the surface layer
                 [real, dimension(:,:)]

    rough      surface roughness length scale (m)   [real, dimension(:,:)]

    u          zonal wind component (m/s) at full model levels at the current time level
                 [real, dimension(:,:,nlev)]

    v          meridional wind component (m/s) at full model levels at the current time level
                 [real, dimension(:,:,nlev)]

    t          temperature (deg K) at full model levels at the current time level
                 [real, dimension(:,:,nlev)]

    q          specific humidity (kg/kg) at full model levels at the current time level
                 [real, dimension(:,:,nlev)]

    um         zonal wind component (m/s) at the previous time level
                 [real, dimension(:,:,nlev)]

    vm         meridional wind component (m/s) at the previous time level
                 [real, dimension(:,:,nlev)]

    tm         temperature (deg K) at the previous time level
                 [real, dimension(:,:,nlev)]

    qm         specific humidity (kg/kg) at the previous time level
                 [real, dimension(:,:,nlev)]

    udt        zonal wind tendency in m/s2
                 [real, dimension(:,:,nlev)]

    vdt        meridional wind tendency in m/s2
                 [real, dimension(:,:,nlev)]

    tdt        temperature tendency in deg k per sec
                 [real, dimension(:,:,nlev)]

    qdt        specific humidity tendency in kg vapor/kg air/sec
                 [real, dimension(:,:,nlev)]

output

    diff_t     diffusion coefficients (m2/s) for heat/moisture/tracers at 
               half model levels, note that there is no surface value
                 [real, dimension(:,:,nlev)]

    diff_m     diffusion coefficients (m2/s) for momentum at 
               half model levels, note that there is no surface value
                 [real, dimension(:,:,nlev)]

    gust       surface layer gustiness (m/s), currently this returns a
               constant value (1 m/s) everywhere
                 [real, dimension(:,:)]

input (optional), for the step-mountain (eta) coordinate option

    mask       mask (1. or 0.) for grid boxes above or below
               the ground, usually only necessary for the step-mountain
               (eta) vertical coordinate  [real, dimension(:,:,nlev)]

    kbot       index of the lowest model level, usually only necessary
               for the step-mountain (eta) vertical coordinate
                 [integer, dimension(:,:)]

---------------------------------------------------------------------

<b>call vert_turb_driver_end</b>

   There are no arguments to this routine.

</PRE>
</A><!-- END ROUTINES -->
<!--------------------------------------------------------------------->
<A NAME="NAMELIST">
<HR>
<H4>NAMELIST</H4>
<!-- BEGIN NAMELIST -->
<PRE>

<b>&vert_turb_driver_nml</b>

  do_mellor_yamada   Switch to to determine when Mellor-Yamada or
                     the generalized diffusivity scheme is used.
                       [logical, default: do_mellor_yamada=.true.]

  do_shallow_conv    Switch to turn on/off shallow convection scheme.
                       [logical, default: do_shallow_conv=.false.]

  gust_scheme        Sets the scheme used for the gustiness calculation.
                     Valid schemes (case sensitive) are:
                     = 'constant' --> use namelist value CONSTANT_GUST
                     = 'beljaars' --> use Beljaars(1994) scheme
                       [character, default: gust_scheme = 'constant']

  constant_gust      Value used for gustiness (in m/s) when
                     gust_scheme = 'constant'.
                       [real, default: constant_gust = 1.]

  use_tau        Switch to determine whether the input data (momentum, temp, sphum)
                 used to computed the diffusion coefficients and/or update TKE should
                 be for the current time level (tau) or next time level (tau+1)
                   if use_tau = true then data at tau is used (e.g., u,v,t,q)
                   if use_tau = false then data at tau+1 is used by explicitly
                                adding the tendency to the data at tau-1
                                (e.g., tt=t+dt*tdt)
                   [logical, default: use_tau=true ]

  do_molecular_diffusion ??????
                   [logical, default: do_molecular_diffusion = .false.]

</PRE>
</A><!-- END NAMELIST -->
<!--------------------------------------------------------------------->
<A NAME="DIAGNOSTICS">
<HR>
<H4>DIAGNOSTIC FIELDS</H4>
<PRE>
Diagnostic fields may be output to a netcdf file by specifying the
module name <b>vert_turb</b> and the desired field names (given below)
in file <b>diag_table</b>. See the documentation for diag_manager.
</PRE>
<!-- BEGIN DIAGNOSTICS -->
<PRE>

Diagnostic fields for module name: <b>vert_turb</b>

   field name     field description
   ----------     -----------------

   tke            turbulent kinetic energy (m2/s2)
   lscale         turbulent length scale (m)
   lscale_0       master length scale (m)
   z_pbl          depth of planetary boundary layer (m)
   gust           gustiness (m/s)
   diff_t         vert diff coeff for temp (m2/s)
   diff_m         vert diff coeff for momentum (m2/s)
   diff_sc        vert diff coeff for shallow conv (m2/s)

Notes:

 1) tke, lscale, and lscale_0 can only be output when the Mellor-Yamada
    scheme is used.

</PRE>
</A><!-- END DIAGNOSTICS -->
<!--------------------------------------------------------------------->
<A NAME="CHANGES">
<HR>
<H4>CHANGE HISTORY</H4>
<!-- BEGIN CHANGES -->
<PRE>

<B>Changes prior to CVS version control</B>

<b>changes</b> (1/24/2000)

  * Minor change.

    When the Mellor-Yamada scheme is NOT selected the Mellor-Yamada
    initialization and end routines are no longer called.

<b>changes</b> (10/4/1999)

  * Major changes.

  * MPP version created. Minor changes for open_file, error_mesg,
    and Fortran write statements. Answers should reproduce the
    previous version.

  * Implementation of the new MPP diagnostics package.
    This required major changes to the diagnostic interface and
    the manner in which diagnostics quantities are selected.
    There are additional arguments to several interfaces.

<b>changes</b> (8/31/1999)

    Diagnostic field z_pbl, the depth of planetary boundary layer,
    may now be output for either the generalized diffusivity scheme
    or the Mellor-Yamada scheme. (In an earlier revision PBL depth
    could only be output for the diffusivity scheme.)

</PRE>
</A><!-- END CHANGES -->
<!--------------------------------------------------------------------->
<A NAME="ERRORS">
<HR>
<H4>ERROR MESSAGES</H4>
<!-- BEGIN ERRORS -->
<PRE>

<b>Fatal errors in vert_turb_driver_init:</b>

    <b>attempting to call initialization twice</b>
       You can not call vert_turb_driver_init more than once.

    <b>invalid value for namelist variable GUST_SCHEME</b>
       The gustiness scheme you have selected is not valid.
       Check the <a href="vert_turb_driver.doc.html#NAMELIST">namelist options</a> for variable GUST_SCHEME.

<b>Fatal errors in vert_turb_driver:</b>

    <b>initialization has not been called</b>
       You have not called vert_turb_driver_init before calling
       vert_turb_driver.

</PRE>
</A><!-- END ERRORS -->
<!--------------------------------------------------------------------->
<A NAME="BUGS">
<HR>
<H4>KNOWN BUGS</H4>
<!-- BEGIN BUGS -->
<PRE>

     There are no known bugs.

</PRE>
</A><!-- END BUGS -->
<!--------------------------------------------------------------------->
<A NAME="PLANS">
<HR>
<H4>FUTURE PLANS</H4>
<!-- BEGIN PLANS -->
<PRE>

     None.

</PRE>
</A><!-- END PLANS -->
<!--------------------------------------------------------------------->

<HR>
</BODY>
</HTML>
